What is Patching & How to a Make Patch…



ResCompare can be used to create a self–applying patch application. You can use the patch to distribute upgrades of your software without sending a new copy of the entire application. Patches are typically 40% of the original file, so you can save disk space and communications upload/download time by sending the patch instead of the entire application. Also, the patch is only useful to owners of the original version, so you can distribute patches to your commercial software over public bulletin boards.

How to Apply a Patch

Patches are easy to apply. Just open a self–applying patch and it displays some notes, then prompts you for the file to patch. A bar graph displays the progress. When done, it tells you if it was suc-cessful. It’s that simple—a real no–brainer.


Creating Self–Applying Patches

Self–applying patches are created with ResCompare’s Make Patch… command. Select the resources that you want included in the patch and choose Make Patch. ResCompare asks if you want to create a new patch or append to an existing patch. If you’re making a new patch, click New. A second dialog lets you set various patch options.

•	You can choose the prompt that the patch will use when asking for the original file. By default, the prompt will be “Where is ‘original file?”, where original file is the name of your master file.

•	You can also choose whether you want the original file to be patched in place, or whether you want the patch application to make a copy first. If you would prefer the patch to make a copy, you can choose a default name for the copy. After opening the original file, the patch will prompt the user to save a copy. If the user replaces the original file, the patch application does not make a copy, but patches the original file in place anyway.

When you click OK, ResCompare asks you to save the patch. It then finds the differences between the selected resources and saves them in the self–applying patch.

One Patch for Many Versions

If you have released several versions of your application, you can create a patch that will work with all released versions. I’ll go through an example that describes the process. Let’s say you have three released versions of your application named Sample: version 1.0, version 1.0.1 and version 1.2. You want to release version 1.3 as a self–applying patch that will upgrade all existing versions.

•	Create the patch “Sample 1.3 patch,” as described above, that patches version 1.0 to 1.0.1.

•	Using ResCompare, compare version 1.0.1 to version 1.2. Select the changed resources and choose Make Patch… When asked if you want to create a new patch, click the Append button and select “Sample 1.3 patch,” which you created in step 1. After opening the patch, you will have an opportunity to adjust the patch options.

•	Repeat step 2 for the changes from version 1.2 to 1.3. You now have a self–applying patch that can upgrade versions 1.0, 1.0.1 and 1.2 of Sample to version 1.3.

An easy way to do this incrementally is:

•	Create the first patch for the first upgrade.

•	When the time comes to release the second upgrade, duplicate the patch for the first upgrade, rename it, and append the new patch information to it.

•	For each subsequent upgrade, always duplicate and rename the last patch you created, and append your changes to it.

One Patch for Many Files

A single patch can also contain the information needed to patch multiple files. Simply compare each additional file and append the patch information, as describe above. The patch options can be set individually for each file you want patched.

Adding Notes to the Patch

Open the patch with a resource editor and edit TEXT/styl resource 128. This resource contains the patch notes that are displayed when the patch is first opened. You can add your own notes here if you like. Remember, leave the paragraph that begins “This patch application was created…” at the end of the notes. Do not alter this paragraph.

Localizing a Patch

You can localize an individual patch by changing its dialog, alert, and string resources. If you would like to create a version of ResCompare that will always generate your localized self–applying patch, follow these steps:

•	Make a small patch and localize all text, except for the resources 'ZVER', 'ZAP#', 'ZIL#', 'ZIS#', and 'ZAP '. You may localize the default patch notes, including the ResCompare notice at the end. Just don’t remove the notice.

•	Open the patch in ResCompare and select all resources except those listed above.

•	Choose the Encapsulate… command from the File menu. This command creates a new resource file and saves the selected resources into it, stripped of their resource types, IDs, and attributes. All selected resources are written to the encapsulated file with the type 'RES '. Also, a resource of type 'RES#' is written to the file, which contains a mapping of each encapsulated resource to its original resource. ResCompare contains a ResEdit template for the 'RES#' resource type, so you can view its contents. See Appendix 1 for a source code listing that will expand an encapsulated resource file back into its original form.

•	Make a copy of ResCompare and open it and the encapsulated patch in ResEdit.

•	Select all 'RES ' and 'RES#' resources from the ResCompare copy and delete them. Select all 'RES ' and 'RES#' resources from the encapsulated patch and copy them to ResCompare. Close and save the ResCompare copy.

ResCompare will now use your localized version each time you create a new patch.
Limitations
Always patch a copy of your application, not the original. Never patch your master disks. Use the “patch a copy” option if your users might not follow this advice.

ResCompare allows you to append patches whose version numbers are not in strict ascending order, but it warns you when it detects this situation. Be sure to test such patches thoroughly, on all intended versions of your application, since this disables version checking.

Self–applying patches work on applications the same way that some viruses do (by mod-ify-ing their CODE resources). Because of this, some virus detectors may get upset when a patch starts doing its thing. Your best bet is to turn off virus protectors and restart before patching. Because of this limitation, please remember to check your floppies for viruses before distributing a patch on them.

The self–applying patch requires some free space on the volume, and it makes every possible attempt to apply the patch within the space provided. However, I have had some reports of problems patching files on a nearly full floppy. I therefore suggest copying the file to your hard disk before patching.